<!DOCTYPE HTML PUBLIC "-//W3C/DTD HTML 4.01//EN">

<html>
<head>
 <title> Pep/8: Debugging Programs Documentation </title>
  <style type="text/css" media="all">
   code { font-family:Courier, 'Courier New', monospace; font-size:11pt }
   img { vertical-align:text-top; }
   h4 { margin-bottom: 0; border-bottom-width: 0; padding-bottom: 0; }
  </style>
</head>
<body bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#000033" alink="#0066FF">
<table bgcolor="#FB9F14" width="100%" cellpadding="2" cellspacing="0" border="0">
<tr><td>
<p style="text-align:center; font-family:helvetica, arial, sans-serif; font-size:14pt; font-weight:bold; color: #29315E">
Debugging Programs
</p>
</td></tr>
</table>
<p>
 The Pep/8 system provides debugging tools to help you locate errors in the programs you write.
 The tools include a memory dump, break points, and a symbolic trace feature.
 If you are debugging a machine language program that you wrote you can use the memory dump feature
 but you cannot set break points or use the symbolic trace feature.
 You can use all the debugging features if you are debugging an assembly language program.
 An additional debugging tool is the byte converter, which is available any time the application is running.
 <p>
 <a name = "Topics">Topics:</a>
 <a href="#Memory">The memory dump</a>,
 <a href="#Break">Break points</a>,
 <a href="#Symbolic">Symbolic trace</a>,
 <a href="#Byte">Byte converter</a>.

<h3><a name="Memory">The memory dump</a></h3>

View the Memory Dump pane by selecting View->Code/CPU/Memory from the menu or by clicking the corresponding icon in the tool bar.
<p>
<img src="images/codecpumemory.png" alt="codecpumemory" hspace=10 vspace=10>
<img src="images/codecpumemoryicon.png" alt="codecpumemoryicon" hspace=10 vspace=10>
<p>
The Pep/8 application may run noticibly slower when the Memory Dump pane is visible.
You can click either of the other two view icons to hide the Memory Dump pane.
<p>
 <img src="images/codecodememory.png" alt="codecodememory" hspace=10 vspace=10>
<p>
You can scroll to any location in memory using the scroll bar on the right.
To scroll to a specific memory location enter the address in hexadecimal
in the input field at the bottom of the pane.
Click the SP button to scroll to the run-time stack.
Click the PC button to scroll to the region of memory pointed to by the program counter.
<p>
<img src="qrc:/help/images/scrollto.png" alt="fig0434" hspace=10 vspace=10>

<h4>Switching to debug mode</h4>
To use the Memory Dump pane you must first switch to the debug mode.
If you are debugging a machine language program that you wrote, the first step is to enter the program in hexadecimal in the Object Code pane.
The following figure shows the object program from Figure 4.34 of the text.
<p>
<img src="qrc:/help/images/fig0434.png" alt="fig0434" hspace=10 vspace=10>
<p>
 Then select Build->Start Debugging Object from the menu, which puts you in the debugging mode.
<p>
<img src="qrc:/help/images/startdebuggingobject.png" alt="startdebuggingobject" hspace=10 vspace=10>
<p>
If you are debugging an assembly language program that you wrote, enter the program in the Source Code pane.
Assemble it by selecting Build->Assemble from the menu or clicking on the hammer icon in the tool bar.
<p>
<img src="qrc:/help/images/assemble.png" alt="assemble" hspace=10 vspace=10>
<img src="qrc:/help/images/assembleicon.png" alt="assembleicon" hspace=10 vspace=10>
<p>
 Then select Build->Start Debugging Source from the menu, or click on the icon with the bug in the toolbar, which puts you in the debugging mode.
<p>
<img src="qrc:/help/images/startdebuggingsource.png" alt="startdebuggingsource" hspace=10 vspace=10>
<img src="qrc:/help/images/startdebuggingicon.png" alt="startdebuggingicon" hspace=10 vspace=10>
<p>
<h4>Tracing in debug mode</h4>
While you are in the debugging mode, you can click the Single Step button in the CPU pane,
which will execute one von Neumann cycle of the CPU.
<p>
<img src="qrc:/help/images/singlestep.png" alt="singlestep" hspace=10 vspace=10>
<p>
 The CPU pane shows you the values of the NZVC bits and of each register in the CPU.
 The following screenshot shows the CPU pane after one click of the Single Step button for the object program from Figure 4.34.
<p>
<img src="qrc:/help/images/fig0434cpu.png" alt="fig0434cpupane" hspace=10 vspace=10>
<p>
The CPU pane displays the content of the accumulator, index register, stack pointer, and program counter first in hexadecimal and
then in decimal.
It displays the instruction specifier first in binary, and then as a mnemonic.
If the instruction is nonunary, it decodes the addressing mode field and shows the corresponding letter for the addressing mode
after the mnemonic, and displays the operand specifier.
<p>
The operand is not part of the CPU, except for the case of immediate addressing when the operand <i>is</i> the operand specifier.
However, for the convenience of the programmer, the CPU pane computes the value of the operand from the addressing mode
and displays it as well.
The Operand field in the CPU pane is enclosed in parentheses to emphasize the fact that it is <i>not</i> part of the CPU.
<p>
<img src="qrc:/help/images/operand.png" alt="operand" hspace=10 vspace=10>
<p>
 The values in the CPU pane are the values <i>after</i> the instruction in the instruction specifier has executed.
 For example, the values in the above screenshots are the values after the first <code>CHARI</code> executes.
 In the von Neumann cycle, the program counter increments before the instruction executes.
 So, the value of the program counter is the address of the <i>next</i> instruction to execute.
 In the above screenshot, the program counter is 3, which is the address of the <i>next</i> instruction to execute,
 while the instruction that just executed is the instruction at address 0.
<p>
 As you single step through the program, the Memory Dump pane highlights in red the bytes that have changed,
 and highlights in blue the bytes of the instruction as specified by the program counter.
 The following screenshot shows the Memory Dump pane after the first click of the Single Step button.
<p>
<img src="qrc:/help/images/fig0434memorydump.png" alt="fig0434memorydump" hspace=10 vspace=10>
<p>
Each line of the Memory Dump pane displays eight bytes, each byte represented as two hexadecimal digits.
The address in the first column is the address of the first byte.
The rightmost column shows the value of the bytes in the row displayed as ASCII characters.
If the byte is a control character that cannot be displayed, the column depicts the value as a period.
<p>
The above screenshot highlights the byte at address 000D in red because the first <code>CHARI</code> instruction
input the letter <code>u</code> at that address.
It hightlights the bytes starting at address 0003 in blue because that is the value of the program counter,
and those bytes are the instruction that will execute <i>next</i>.
<p>
The Memory Dump pane also highlights the top byte of the stack in magenta.
The following screenshot from Figure 6.1 shows the stack starting at address FBCE just before the <code>ADDSP</code> executes.
<p>
<img src="qrc:/help/images/fig0601.png" alt="fig0601" hspace=10 vspace=10>
<p>
 <h4>Switching out of debug mode</h4>
 If you want the program to run to completion, click the Resume button.
 The program will run to completion and exit the debug mode.
<p>
<img src="qrc:/help/images/resume.png" alt="resume" hspace=10 vspace=10>
<p>
 If you want to terminate the debugging session without running the program to completion, select Build->Stop Debugging
 from the menu or click the stop sign icon in the menu bar.
<p>
<img src="qrc:/help/images/stopdebugging.png" alt="stopdebugging" hspace=10 vspace=10>
<img src="qrc:/help/images/stopdebuggingicon.png" alt="stopdebuggingicon" hspace=10 vspace=10>
<p>
<a href="#Topics">Scroll to topics</a>.
<p>
<h3><a name="Break">Break points</a></h3>
To use break points for an assembly language program enter the debugging mode as described in the previous section.
Pep/8 will switch from the Code pane to the Trace pane and display the source program for tracing.
The following screenshot shows the Trace pane for the program in Figure 5.15 of the text.
<p>
<img src="qrc:/help/images/fig0515listingtrace.png" alt="fig0515listingtrace" hspace=10 vspace=10>
<p>
As you single step through the program, the CPU shows the content of the registers as described in the previous section.
Remember that the CPU pane shows the values of the registers <i>after</i> the instruction in the instruction specifier
has executed.
In addition, the Trace pane highlights the instruction specified by the program counter, which is the <i>next</i> instruction
to be executed.
The following screenshot shows the Trace pane after five clicks of the Single Step button.
The <code>LDA</code> instruction has just executed, and the <code>ADDA</code> instruction will execute next.
<p>
<img src="qrc:/help/images/fig0515listingadda.png" alt="fig0515listingadda" hspace=10 vspace=10>
<img src="qrc:/help/images/fig0515cpu.png" alt="fig0515cpu" hspace=10 vspace=10>

<p>
<h4>Setting break points</h4>
 Each executable instruction in the Trace pane has a checkbox for setting a break point.
 The following screenshot shows the Trace pane for the program in Figure 5.15 before any statement has been executed.
 The programmer has set a breakpoint at the <code>STA</code> instruction.
<p>
<img src="qrc:/help/images/fig0515breakpoint.png" alt="fig0515breakpoint" hspace=10 vspace=10>
<p>
 When the programmer clicks the Resume button, the program resumes executing until it gets to an instruction with a breakpoint
 or until completion if no breakpoint is encountered.
 The following screenshots show what happens when the Resume button is clicked.
 Note that the <code>STA</code> instruction will execute next if the programmer clicks the Single Step button at this point.
 <p>
<img src="qrc:/help/images/resume.png" alt="resume" hspace=10 vspace=10>
<img src="qrc:/help/images/fig0515resumed.png" alt="fig0515resumed" hspace=10 vspace=10>
<p>
<h4>Tracing traps</h4>
 If you want to trace the operating system's execution of a trap instruction, click the Trace Traps checkbox in the CPU pane before
 entering the debugging mode.
 <p>
<img src="qrc:/help/images/tracetraps.png" alt="tracetraps" hspace=10 vspace=10>
<p>
As you single step through your program, if you execute a trap instruction the Trace pane will show the individual instructions
in the trap handler of the operating system.
The following screenshot shows the <code>DECI</code> instruction about to be executed.
<p>
<img src="qrc:/help/images/fig0515deci.png" alt="fig0515deci" hspace=10 vspace=10>
<p>
Clicking the Single Step button at this point causes the Trace pane to switch to the trap handler in the operating system.
The screenshot below shows the Trace pane after clicking the Single Step button.
It highlights the first instruction in the trap handler of the operating system.
<p>
<img src="qrc:/help/images/fig0515trap.png" alt="fig0515trap" hspace=10 vspace=10>
<p>
When you are tracing an operating system trap, you can set breakpoints and click Single Step or Resume as you would
with the source program.
If you resume within the operating system and encounter no further breakpoints, Pep/8 will continue after the return
from trap instruction <code>RETTR</code>
to the source program until it encounters a break point there.
<p>
<a href="#Topics">Scroll to topics</a>.

<h3><a name="Symbolic">Symbolic trace</a></h3>

The symbolic trace feature is controlled by the trace tags described in the text.
Trace tags are contained in assembly language comments and have no effect on generated object code.
Each trace tag begins with the <code>#</code> character and supplies information to the symbol tracer on how to format
and label the memory cell in the trace window.
<p>
If your program does not include trace tags, the memory trace pane will not be visible when you run your program.
You can still use the debugger to single-step through your program and set break points.
If it does include trace tags, but errors are detected in the tags, a blue warning will be issued.
You can still run your program and use the debugger, but the memory trace pane will not be visible.
The screenshot below shows what happens if you make an error in one of the trace tags in the program from Figure 5.26.
<p>
<img src="qrc:/help/images/fig518tracetagwarning.png" alt="fig518tracetagwarning" hspace=10 vspace=10>
<p>
If your program does include trace tags and they have no errors, the memory trace will automatically become visible
below the listing trace pane.
As you single-step through the program, you can see the global variables on the left, and the run-time stack on the right.
The only user interface control that affects the symbolic trace display is the magnification input at the bottom left of the pane.
Here is a screenshot of the memory trace pane from the program in Figure 6.21.
The memory cell for <code>k</code> on top of the run-time stack is colored red because the <code>STA</code>
instruction has just changed its value.
<p>
<img src="qrc:/help/images/memorytrace.png" alt="memorytrace" hspace=10 vspace=10>
<p>
 The sybolic trace feature displays global variables allocated with the <code>.BLOCK</code> dot command,
 parameters and local variables allocated with the <code>SUBSP</code> instruction, the fields of a global <code>struct</code>,
 and storage from the heap allocated with the <code>new</code> operator.
 See the text for information on how to use trace tags in your programs.
<p>
<a href="#Topics">Scroll to topics</a>.

<h3><a name="Byte">Byte converter</a></h3>

Any time the Pep/8 application is running, the byte converter is available in the tool bar.
The four input fields represent the value of a single byte as displayed from left to right in decimal, hexadecimal, binary, and ASCII.
Simply enter any value in any input field and the other fields will show the same value in the corresponding format.
Here is the result of entering the letter <code>P</code> in the ASCII field.
 <p>
<img src="qrc:/help/images/byteconverter.png" alt="byteconverter" hspace=10 vspace=10>
<p>
An instruction specifier decoder is to the right of the four input fields.
It displays the instruction mnemonic and possibly the addressing mode assuming you interpret the byte value as an instruction specifier.
<p>
<a href="#Topics">Scroll to topics</a>.
<p>

</body>
</html>
